home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #5 & #6 / Amiga Plus CD - 1995 - No. 5 and 6.iso / pd / daten / astrolog / src / astdev.doc < prev    next >
Text File  |  1995-08-11  |  11KB  |  462 lines
  1. TABLE OF CONTENTS
  2.  
  3. amiga/AmigaClearScreen
  4. amiga/AmigaDisplayExit
  5. amiga/AmigaDisplayInit
  6. amiga/AmigaDisplayPaging
  7. amiga/AmigaDisplayResize
  8. amiga/AmigaDisplayUpdate
  9. amiga/AmigaGetKey
  10. rastport/rp_dispose
  11. rastport/rp_new
  12. xtras/xPrint
  13. xtras/xPrintAt
  14. xtras/xPutString
  15. amiga/AmigaClearScreen                                    amiga/AmigaClearScreen
  16.  
  17.    NAME
  18.         AmigaClearScreen -- Clear Astrolog's Amiga graphics display
  19.  
  20.    SYNOPSIS
  21.         AmigaClearScreen();
  22.  
  23.         void AmigaClearScreen(void);
  24.  
  25.    FUNCTION
  26.         This procedure unsets all pixels in the drawing page.
  27.  
  28.    INPUTS
  29.         none
  30.  
  31.    RESULT
  32.         none
  33.  
  34.    EXAMPLE
  35.  
  36.    NOTES
  37.         Calling this function is usually faster than painting a rectangle
  38.         covering the whole screen.
  39.  
  40.    BUGS
  41.  
  42.    SEE ALSO
  43.         AmigaDisplayPaging()
  44.  
  45. amiga/AmigaDisplayExit                                    amiga/AmigaDisplayExit
  46.  
  47.    NAME
  48.         AmigaDisplayExit -- Dispose Astrolog's Amiga graphics stuff
  49.  
  50.    SYNOPSIS
  51.         AmigaDisplayExit();
  52.  
  53.         void AmigaDisplayExit(void);
  54.  
  55.    FUNCTION
  56.         This function closes Astrolog's window and screen which had been
  57.         provided via AmigaDisplayInit().  If paging is on, i.e. a 2nd
  58.         page has been provided for animations, then this page is disposed
  59.         as well.
  60.  
  61.    INPUTS
  62.         none
  63.  
  64.    RESULT
  65.         none
  66.  
  67.    EXAMPLE
  68.         #include "astrolog.h"
  69.  
  70.         /* ... */
  71.  
  72.         if( AmigaDisplayInit() == 0 )
  73.         {
  74.            /* do some gfx... */
  75.  
  76.            AmigaDisplayExit();
  77.         }
  78.         else error();
  79.  
  80.    NOTES
  81.  
  82.    BUGS
  83.  
  84.    SEE ALSO
  85.         AmigaDisplayInit()
  86.  
  87. amiga/AmigaDisplayInit                                    amiga/AmigaDisplayInit
  88.  
  89.    NAME
  90.         AmigaDisplayInit -- Initialize an Amiga screen for Astrolog charts
  91.  
  92.    SYNOPSIS
  93.         error= AmigaDisplayInit();
  94.  
  95.         int AmigaDisplayInit(void);
  96.  
  97.    FUNCTION
  98.         This function opens an Amiga screen with an EGA palette and a sizable
  99.         window which is large enough to hold `gs.xWin' pixel columns and
  100.         `gs.yWin' pixel rows.  If this should fail for any reason, an error
  101.         code != 0 is returned.
  102.  
  103.    INPUTS
  104.         none
  105.  
  106.    RESULT
  107.         error - != 0 in case of an error,  0 otherwise
  108.  
  109.    EXAMPLE
  110.         #include "astrolog.h"
  111.  
  112.         /* ... */
  113.  
  114.         if( AmigaDisplayInit() == 0 )
  115.         {
  116.            /* do some gfx... */
  117.  
  118.            AmigaDisplayExit();
  119.         }
  120.         else error();
  121.  
  122.    NOTES
  123.         Hack: The EGA colors provided for the screen are taken from the
  124.         global rgbbmp[] array (see xdata.c).  However, if the `us.fAnsi' flag
  125.         is set, a slightly brighter palette is used.
  126.  
  127.         Note also that this function sets `us.fAnsi' to `fFalse' to make sure
  128.         that no ANSI characters are used in the graphic chart mode.  The
  129.         initial value of `us.fAnsi' is resored by AmigaDisplayExit().
  130.  
  131.    BUGS
  132.  
  133.    SEE ALSO
  134.         AmigaDisplayExit()
  135.  
  136. amiga/AmigaDisplayPaging                                amiga/AmigaDisplayPaging
  137.  
  138.    NAME
  139.         AmigaDisplayPaging -- Allocate or free the page for animations
  140.  
  141.    SYNOPSIS
  142.         paging= AmigaDisplayPaging();
  143.  
  144.         int AmigaDisplayPaging(void);
  145.  
  146.    FUNCTION
  147.         Here we allocate a 2nd rastport for double buffering.  All Amiga
  148.         drawing happens in `gi.rp' and here we replace `gi.rp' with a newly
  149.         allocated rastport which has the same size as the one of the astrolog
  150.         screen `gi.scr'.  Since paging is mainly used for animation purposes,
  151.         we also add the INTUITICKS bit to our window's IDCMP port.
  152.         Failure due to low memory is no fatal error because double buffering is
  153.         only a bonus for the animations.
  154.  
  155.    INPUTS
  156.         none
  157.  
  158.    RESULT
  159.         paging - 0 if we disabled paging with this call, !=0 otherwise.
  160.  
  161.    EXAMPLE
  162.         #include "astrolog.h"
  163.  
  164.         /* ... */
  165.  
  166.         if( AmigaDisplayInit() == 0 )
  167.         {
  168.           /* switch to double buffering mode */
  169.  
  170.           if(!gi.paging)
  171.             AmigaDisplayPaging();
  172.  
  173.           /* do some anim stuff... */
  174.  
  175.           AmigaDisplayExit();
  176.         }
  177.         else error();
  178.  
  179.    NOTES
  180.  
  181.    BUGS
  182.  
  183.    SEE ALSO
  184.         AmigaDisplayPaging(), AmigaDisplayExit()
  185.  
  186. amiga/AmigaDisplayResize                                amiga/AmigaDisplayResize
  187.  
  188.    NAME
  189.         AmigaDisplayResize -- Guarantee certain graphic display dimensions
  190.  
  191.    SYNOPSIS
  192.         error= AmigaDisplayResize(width, height);
  193.  
  194.         int AmigaDisplayResize(int, int);
  195.  
  196.    FUNCTION
  197.         This function makes sure that the Amiga graphics page (screen and
  198.         window) are large enough to hold a graphic with `width' pixels
  199.         horizontally and `height' pixels vertically.  If the current screen
  200.         is large enough, nothing happens.  Otherwise it will be enlarged
  201.         to the given size.
  202.  
  203.    INPUTS
  204.         none
  205.  
  206.    RESULT
  207.         error - != 0 in case of an error,  0 otherwise
  208.  
  209.    EXAMPLE
  210.  
  211.    NOTES
  212.  
  213.    BUGS
  214.  
  215.    SEE ALSO
  216.         AmigaDisplayInit(), AmigaDisplayExit()
  217.  
  218. amiga/AmigaDisplayUpdate                                amiga/AmigaDisplayUpdate
  219.  
  220.    NAME
  221.         AmigaDisplayUpdate -- Display the temporary drawing page
  222.  
  223.    SYNOPSIS
  224.         AmigaDisplayUpdate();
  225.  
  226.         void AmigaDisplayUpdate(void);
  227.  
  228.    FUNCTION
  229.         If double buffering is enabled, then the hidden page (which is the
  230.         one we use to paint on) will be copied to the currently visible page.
  231.         Without any 2nd page, calling this procedure is a no-op.
  232.  
  233.    INPUTS
  234.         none
  235.  
  236.    RESULT
  237.         none
  238.  
  239.    EXAMPLE
  240.  
  241.    NOTES
  242.  
  243.    BUGS
  244.  
  245.    SEE ALSO
  246.         AmigaDisplayPaging()
  247.  
  248. amiga/AmigaGetKey                                              amiga/AmigaGetKey
  249.  
  250.    NAME
  251.         AmigaGetKey -- Wait for a keypress and return it's ASCII code
  252.  
  253.    SYNOPSIS
  254.         key= AmigaGetKey();
  255.  
  256.         int AmigaGetKey(void);
  257.  
  258.    FUNCTION
  259.         Wait for a keypress and return the ASCII code of that key.  This
  260.         function distinguishes between console mode and graphics mode and
  261.         calls getkey() if there is no graphics window.
  262.  
  263.    INPUTS
  264.         none
  265.  
  266.    RESULT
  267.         key   - The ASCII code of the character on the pressed key
  268.  
  269.    EXAMPLE
  270.  
  271.    NOTES
  272.  
  273.    BUGS
  274.  
  275.    SEE ALSO
  276.         getkey()
  277.  
  278. rastport/rp_dispose                                          rastport/rp_dispose
  279.  
  280.    NAME
  281.         rp_dispose -- Free a RastPort allocated via rp_new()
  282.  
  283.    SYNOPSIS
  284.         nil= rp_dispose(rp);
  285.  
  286.         struct RastPort *rp_dispose(struct RastPort *);
  287.  
  288.    FUNCTION
  289.         This function returns all memory allocated for the given RastPort,
  290.         the attached rp->BitMap and all bitplanes to the system free pool.
  291.  
  292.    INPUTS
  293.         rp            - A RastPort allocated vi rp_new()
  294.  
  295.    RESULT
  296.         nil           - if rp has been allocated via rp_new() then
  297.                         (struct RastPort *)NULL will be returned,
  298.                         rp (unchanged), otherwise.
  299.  
  300.    EXAMPLE
  301.  
  302.    NOTES
  303.  
  304.    BUGS
  305.  
  306.    SEE ALSO
  307.         rp_new()
  308.  
  309. rastport/rp_new                                                  rastport/rp_new
  310.  
  311.    NAME
  312.         rp_new -- Allocate a RastPort including a BitMap and Bitplanes
  313.  
  314.    SYNOPSIS
  315.         rp= rp_new(width, height, depth);
  316.  
  317.         struct RastPort *rp_new(int, int, int);
  318.  
  319.    FUNCTION
  320.         This function allocates a new RastPort and attaches a new BitMap to
  321.         it with initialized, empty bitplanes.
  322.  
  323.    INPUTS
  324.         width         -
  325.         height        -
  326.         depth         -
  327.  
  328.    RESULT
  329.         rp            - A new RastPort
  330.  
  331.    EXAMPLE
  332.  
  333.    NOTES
  334.  
  335.    BUGS
  336.  
  337.    SEE ALSO
  338.         rp_dispose()
  339.  
  340. xtras/xPrint                                                        xtras/xPrint
  341.  
  342.    NAME
  343.         xPrint -- Render a format string to astrolog's graphic screen
  344.  
  345.    SYNOPSIS
  346.         xPrint(fmt,...);
  347.  
  348.         void xPrint(char *,...);
  349.  
  350.    FUNCTION
  351.         This procedure does basically the same as xPutString(), i.e. it
  352.         renders a string to the graphic screen, using astrolog's internal
  353.         font.  The difference between xPutString() and xPrint() is that
  354.         xPrint() performs printf() like substitutions in the given
  355.         format string `fmt'.
  356.  
  357.    INPUTS
  358.         fmt   - A printf() like format string and
  359.         ...     it's arguments
  360.  
  361.    RESULT
  362.         none
  363.  
  364.    EXAMPLE
  365.  
  366.    NOTES
  367.  
  368.    BUGS
  369.  
  370.    SEE ALSO
  371.         xPutString(), xPrintAt()
  372.  
  373. xtras/xPrintAt                                                    xtras/xPrintAt
  374.  
  375.    NAME
  376.         xPrintAt -- Render format string at given position on the screen
  377.  
  378.    SYNOPSIS
  379.         xPrintAt(line,column, fmt,...);
  380.  
  381.         void xPrintAt(int,int, char *,...);
  382.  
  383.    FUNCTION
  384.         This procedure moves an invisible cursor to given location
  385.         (line,column) on astrolog's screen and renders the format string
  386.         `fmt' at this location via xPutString() after expanding it using
  387.         the given arguments `...' (if present).
  388.  
  389.    INPUTS
  390.         line,column   - The position where the first character shall be
  391.                         rendered on the screen
  392.         fmt           - A printf() like format string and
  393.         ...             it's arguments
  394.  
  395.    RESULT
  396.         none
  397.  
  398.    EXAMPLE
  399.         xPrintAt(5,3,"{green}I compute {white}1+1={red}%d{green}.",1+1);
  400.  
  401.    NOTES
  402.         You should *always* use xPrintAt() before using either xPrint()
  403.         or xPutString() in order to initialize the cursor position.
  404.  
  405.    BUGS
  406.  
  407.    SEE ALSO
  408.         xPutString(), xPrint()
  409.  
  410. xtras/xPutString                                                xtras/xPutString
  411.  
  412.    NAME
  413.         xPutString -- Render text on the graphic screen
  414.  
  415.    SYNOPSIS
  416.         xPutString(str);
  417.  
  418.         void xPutString(char *);
  419.  
  420.    FUNCTION
  421.         This procedure prints given string `str' onto astrolog's graphic chart
  422.         display at the position where the previous call's output ended.  I.e.:
  423.         xPutString() has an invisible cursor which is advanced to the end of
  424.         it's output, each time you call this function.  The usual "escaped"
  425.         character sequences (like '\n' ot '\b') are handled by this function
  426.         as well.
  427.  
  428.         The text is rendered using the current pen as set via DrawColor().
  429.         However, some special macros can be used to change the color within
  430.         a string.  These macros are:
  431.  
  432.              {black}     kBlack               {dkgray}    kDkGray
  433.              {maroon}    kMaroon              {red}       kRed
  434.              {dkgreen}   kDkGreen             {green}     kGreen
  435.              {orange}    kOrange              {yellow}    kYellow
  436.              {dkblue}    kDkBlue              {blue}      kBlue
  437.              {purple}    kPurple              {magenta}   kMagenta
  438.              {dkcyan}    kDkCyan              {cyan}      kCyan
  439.              {ltgray}    kLtGray              {white}     kWhite
  440.  
  441.    INPUTS
  442.         str   - The string to render
  443.  
  444.    RESULT
  445.         none
  446.  
  447.    EXAMPLE
  448.         xPrintAt(3,5,"");   /* initialize cursor position */
  449.         xPutSting("This text is rendered using the current color,\n"
  450.                   "{white}whereas {red}this {green}changes {purple}it");
  451.  
  452.    NOTES
  453.         xPutString() restores the initial pen if a color macro changes it.
  454.         So xPutString("{red}") is not the same as DrawColor(kRed).
  455.  
  456.    BUGS
  457.         '\t' is not implemented.
  458.  
  459.    SEE ALSO
  460.         xPrint(), xPrintAt()
  461.  
  462.